/**
 * @file command_executor.h
 * @brief ESP32沙画机命令执行器头文件
 * 
 * 重构优化亮点 (2025-09-22):
 * ===========================
 * - PatternAction枚举: 统一扫图模式的图案操作类型
 * - 核心扫图函数: executeSweepAndPrepareCore() 消除重复代码
 * - 状态管理辅助函数: 集中化设备状态和LED状态管理
 * - 提升代码可维护性和一致性
 */

#ifndef COMMAND_EXECUTOR_H
#define COMMAND_EXECUTOR_H

#include <Arduino.h>
#include <ArduinoJson.h>
#include "pattern_loader.h"
#include "motion_controller.h"
#include "wifi_manager.h"
#include "led_manager.h"
#include "led_control_center.h"
#include "device_state_manager.h"
#include "command_executor_performance.h"
#include <Preferences.h>

// 前向声明避免循环依赖
class SerialCommandHandler;

/**
 * 公共命令执行器类
 * 包含所有命令的具体实现，可被串口命令处理器和MQTT管理器共同使用
 */
class CommandExecutor {
private:
    // 组件引用
    PatternLoader* patternLoader;
    MotionController* motionController;  // 统一电机控制器：绘图+归零+管理
    WiFiManager* wifiManager;
    LEDManager* ledManager;              // LED硬件驱动层（保留用于特殊硬件操作）
    LEDControlCenter* ledControlCenter;  // LED业务逻辑层（主要使用）
    DeviceStateManager* deviceStateManager;
    Preferences* preferences;
    
    // 系统状态引用
    bool* systemPowerEnabled;
    bool* isDrawingActive;
    bool* isDrawingPaused;
    int* pausedAtIndex;
    bool* isStreamMode;
    
    // 绘图过程中接收到的命令 - 已弃用
    // String pendingCommand;
    
    // 网络任务处理回调函数（用于在绘图过程中处理MQTT等网络任务）
    void (*networkTaskCallback)();
    
    // 自动播放命令执行回调函数
    void (*autoPlayCommandCallback)(const String&);
    
    // 🚨 命令互斥保护机制
    static bool commandInProgress;           // 命令执行中标志
    static unsigned long lastCommandTime;   // 上次命令执行时间
    static String lastExecutedCommand;      // 上次执行的命令
    static const unsigned long COMMAND_DEBOUNCE_MS = 500; // 命令防抖时间500ms
    
    // ==================== 绘图上下文管理 ====================
    
    /**
     * 绘图上下文类型枚举（通用版）
     */
    enum DrawingContextState {
        NONE = 0,           // 无上下文
        ACTIVE              // 有活跃的绘图上下文
    };
    
    enum DrawingPhase {
        PHASE_NONE = 0,     // 无阶段
        PHASE_SWEEPING,     // 扫图阶段
        PHASE_DRAWING       // 绘图阶段
    };
    
    /**
     * 扫图模式图案操作类型
     */
    enum PatternAction {
        KEEP_CURRENT = 0,   // 保持当前图案（sweepprep）
        SWITCH_TO_PREV,     // 切换到上一个图案（sweepprev）
        SWITCH_TO_NEXT      // 切换到下一个图案（sweepnext）
    };
    
    /**
     * 自动循环播放配置
     */
    struct AutoPlayConfig {
        bool enabled;                    // 是否启用自动循环播放
        unsigned long displayTimeMs;    // 展示时间（毫秒）
        bool useSweepMode;              // 是否使用扫图模式（sweepnext vs next）
        
        // 构造函数设置默认值
        AutoPlayConfig() {
            enabled = false;             // 默认关闭
            displayTimeMs = 5 * 60 * 1000; // 默认5分钟
            useSweepMode = true;         // 默认使用扫图模式
        }
    };
    
    /**
     * 自动恢复配置
     */
    struct AutoResumeConfig {
        bool enabled;                    // 是否启用自动恢复功能
        unsigned long delayMs;          // 暂停后自动恢复的延迟时间（毫秒）
        unsigned long pauseStartTime;   // 暂停开始的时间戳
        bool isWaitingForResume;        // 是否正在等待自动恢复
        
        // 构造函数设置默认值
        AutoResumeConfig() {
            enabled = false;             // 默认关闭
            delayMs = 60 * 1000;        // 默认1分钟
            pauseStartTime = 0;
            isWaitingForResume = false;
        }
    };
    
    /**
     * 绘图上下文状态结构（增强版）
     */
    struct DrawingContext {
        DrawingContextState state;   // 上下文状态：NONE/ACTIVE
        String lastCommand;          // 上一个执行的命令（用于继续逻辑）
        DrawingPhase phase;          // 当前所处的阶段：扫图/绘图
        
        DrawingContext() {
            state = NONE;
            lastCommand = "";
            phase = PHASE_NONE;
        }
        
        void clear() {
            state = NONE;
            lastCommand = "";
            phase = PHASE_NONE;
        }
        
        void setCommand(const String& command) {
            state = ACTIVE;
            lastCommand = command;
            // 🔧 关键修复：只有在没有阶段信息时才根据命令类型设置默认阶段
            // 这样可以保持暂停恢复时的正确阶段信息
            if (phase == PHASE_NONE) {
                // 根据命令类型设置默认阶段
                if (command.startsWith("sweep")) {
                    phase = PHASE_SWEEPING;
                } else {
                    phase = PHASE_DRAWING;
                }
            }
        }
        
        void setPhase(DrawingPhase newPhase) {
            phase = newPhase;
        }
    };
    
    DrawingContext currentContext;   // 当前绘图上下文
    
    // ==================== 自动循环播放管理 ====================
    AutoPlayConfig autoPlayConfig;           // 自动循环播放配置
    unsigned long drawingCompletedTime;      // 绘图完成时间戳
    bool autoPlayWaiting;                    // 是否在等待自动播放
    String lastAutoPlayCommand;              // 最后执行的命令（用于判断扫图模式）
    
    // ==================== 自动恢复管理 ====================
    AutoResumeConfig autoResumeConfig;       // 自动恢复配置
    
    // ==================== 🔧 独立电机控制线程 ====================
    TaskHandle_t motorTaskHandle;            // 电机控制任务句柄
    static void motorControlTask(void* parameter);  // 静态任务函数
    bool motorTaskRunning;                   // 电机任务运行状态
    SemaphoreHandle_t motorMutex;           // 电机访问互斥锁

public:
    // 🚨 命令互斥保护函数
    bool isCommandAllowed(const String& command);
    void markCommandStart(const String& command);
    void markCommandEnd();
    bool isSystemBusy() const;

    /**
     * 构造函数
     */
    CommandExecutor(
        PatternLoader* loader,
        MotionController* motion,  // 统一使用MotionController：绘图+归零+管理
        WiFiManager* wifi,
        LEDManager* led,               // LED硬件驱动层
        LEDControlCenter* ledControl,  // LED业务逻辑层
        DeviceStateManager* stateManager,
        Preferences* prefs,
        bool* sysPowerEnabled,
        bool* drawingActive,
        bool* drawingPaused,
        int* pausedIdx,
        bool* streamMode
    );
    
    /**
     * 设置网络任务处理回调函数（用于在绘图过程中处理MQTT等网络任务）
     * @param callback 回调函数指针
     */
    void setNetworkTaskCallback(void (*callback)());
    
    // ==================== 自动循环播放控制 ====================
    
    /**
     * 设置自动循环播放配置
     * @param enabled 是否启用自动循环播放
     * @param displayTimeMinutes 展示时间（分钟）
     * @param useSweepMode 是否使用扫图模式
     */
    void setAutoPlayConfig(bool enabled, int displayTimeMinutes = 5, bool useSweepMode = true);
    
    /**
     * 获取自动循环播放配置
     * @return AutoPlayConfig 当前配置
     */
    AutoPlayConfig getAutoPlayConfig() const;
    
    /**
     * 更新自动播放状态（需要在主循环中定期调用）
     */
    void updateAutoPlay();
    
    /**
     * 停止自动播放等待
     */
    void stopAutoPlay();
    
    /**
     * 记录最后执行的命令（用于自动播放判断）
     * @param command 执行的命令
     */
    void recordLastCommand(const String& command);
    
    /**
     * 设置自动播放命令执行回调函数
     * @param callback 回调函数指针，接收命令字符串参数
     */
    void setAutoPlayCommandCallback(void (*callback)(const String&));
    
    // ==================== 🔧 独立电机控制线程管理 ====================
    
    /**
     * 启动独立电机控制线程
     * @return true 启动成功，false 启动失败
     */
    bool startMotorControlTask();
    
    /**
     * 停止独立电机控制线程
     */
    void stopMotorControlTask();
    
    /**
     * 检查电机控制线程是否运行
     * @return true 正在运行，false 未运行
     */
    bool isMotorTaskRunning() const;
    
    // ==================== 自动恢复控制 ====================
    
    /**
     * 设置自动恢复配置
     * @param enabled 是否启用自动恢复功能
     * @param delaySeconds 暂停后自动恢复的延迟时间（秒）
     */
    void setAutoResumeConfig(bool enabled, int delaySeconds = 60);
    
    /**
     * 获取自动恢复配置
     * @return AutoResumeConfig 当前配置
     */
    AutoResumeConfig getAutoResumeConfig() const;
    
    /**
     * 更新自动恢复状态（需要在主循环中定期调用）
     */
    void updateAutoResume();
    
    /**
     * 开始自动恢复等待（在暂停时调用）
     */
    void startAutoResumeWait();
    
    /**
     * 停止自动恢复等待
     */
    void stopAutoResumeWait();
    
    /**
     * 检查是否正在等待自动恢复
     * @return 是否正在等待自动恢复
     */
    bool isWaitingForAutoResume() const;

    
    // ==================== 绘图控制命令 ====================
    
    /**
     * 执行开始绘图命令
     * @return 执行结果状态码 (0:成功, 1:系统休眠, 2:无图案, 3:SD卡错误)
     */
    int executeStartCommand(bool skipHoming = false);
    
    /**
     * 执行停止命令
     * @return 执行结果状态码 (0:成功)
     */
    int executeStopCommand();
    
    /**
     * 执行暂停命令（与停止相同）
     * @return 执行结果状态码 (0:成功)
     */
    int executePauseCommand();
    
    /**
     * 执行回零命令
     * @return 执行结果状态码 (0:成功, 1:控制器错误)
     */
    int executeHomeCommand();
    
    /**
     * 执行扫图命令 - 整理沙盘表面
     * @return 执行结果状态码 (0:成功, 1:系统休眠, 2:控制器错误)
     */
    int executeSweepCommand();
    
    /**
     * 执行扫图并准备命令 - 完整流程：归零→扫图→归零→准备绘图
     * @return 执行结果状态码 (0:成功, 1:系统休眠, 2:控制器错误)
     */
    int executeSweepAndPrepareCommand();
    

    
    /**
     * 扫图准备核心函数 - 统一处理所有扫图变体
     * @param action 图案操作类型：保持当前/切换到上一个/切换到下一个
     * @return 执行结果状态码 (0:成功, 1:系统休眠, 2:控制器错误)
     */
    int executeSweepAndPrepareCore(PatternAction action);
    
    /**
     * 执行扫图准备命令 - 支持暂停恢复的智能版本
     * 根据暂停时的阶段决定行为：
     * - 如果在扫图阶段暂停：继续扫图
     * - 如果在绘图阶段暂停：继续绘图
     * - 如果无暂停状态：执行完整扫图流程
     * @return 执行结果状态码 (0:成功, 1:系统休眠, 2:控制器错误)
     */
    
    /**
     * 执行扫图并准备命令（切换到上一个图案）- 完整流程：归零→扫图→加载上一个图案→归零→准备绘图
     * @return 执行结果状态码 (0:成功, 1:系统休眠, 2:控制器错误)
     */
    int executeSweepAndPrepareWithPrevPattern();
    
    /**
     * 执行扫图上一个图案命令 - 支持暂停恢复的智能版本
     * @return 执行结果状态码 (0:成功, 1:系统休眠, 2:控制器错误)
     */
    int executeSweepPrevCommand();
    
    /**
     * 执行扫图并准备命令（切换到下一个图案）- 完整流程：归零→扫图→加载下一个图案→归零→准备绘图
     * @return 执行结果状态码 (0:成功, 1:系统休眠, 2:控制器错误)
     */
    int executeSweepAndPrepareWithNextPattern();
    
    /**
     * 执行扫图下一个图案命令 - 支持暂停恢复的智能版本
     * @return 执行结果状态码 (0:成功, 1:系统休眠, 2:控制器错误)
     */
    int executeSweepNextCommand();
    
    // 已删除重复的固定扫图函数
    
    /**
     * 执行流式扫图 - 基于THR文件数据，支持暂停恢复
     * 参考executeStreamDrawing()的逻辑结构，但使用THRSweepPoint数据
     * 支持LED实时更新、串口命令响应、优雅暂停恢复
     */
    int executeStreamSweepFromTHR(); // 返回: 0=成功, 1=暂停, 2=错误
    
    // ==================== 图案管理命令 ====================
    
    /**
     * 获取图案文件列表
     * @return 图案文件名列表
     */
    std::vector<String> getPatternList();
    
    /**
     * 加载指定图案文件
     * @param filename 图案文件名
     * @return 执行结果状态码 (0:成功, 1:SD卡错误, 2:文件不存在)
     */
    int loadPattern(const String& filename);
    
    /**
     * 获取下一个图案文件名
     * @return 下一个图案文件名
     */
    String getNextPattern();
    
    /**
     * 获取上一个图案文件名
     * @return 上一个图案文件名
     */
    String getPreviousPattern();
    
    /**
     * 加载下一个图案
     * @return 执行结果状态码 (0:成功, 1:无图案, 2:加载失败)
     */
    int loadNextPattern();
    
    /**
     * 加载上一个图案
     * @return 执行结果状态码 (0:成功, 1:无图案, 2:加载失败)
     */
    int loadPreviousPattern();
    
    /**
     * 执行下一个图案命令 (MQTT和串口通用)
     * @return 执行结果状态码 (0:成功, 1:无图案, 2:加载失败)
     */
    int executeNextCommand();
    
    /**
     * 执行上一个图案命令 (MQTT和串口通用)
     * @return 执行结果状态码 (0:成功, 1:无图案, 2:加载失败)
     */
    int executePrevCommand();
    
    /**
     * 执行加载图案命令 (MQTT和串口通用)
     * @param filename 图案文件名
     * @return 执行结果状态码 (0:成功, 1:SD卡错误, 2:文件不存在)
     */
    int executeLoadCommand(const String& filename);
    
    // ==================== 电机控制命令 ====================
    
    /**
     * 启用电机
     * @return 执行结果状态码 (0:成功, 1:控制器错误)
     */
    int enableMotors();
    
    /**
     * 禁用电机
     * @return 执行结果状态码 (0:成功, 1:控制器错误)
     */
    int disableMotors();
    
    /**
     * 移动到指定的极坐标位置
     * @param theta 角度(弧度)
     * @param rho 半径(0.0-1.0)
     * @return 执行结果状态码 (0:成功, 1:系统休眠, 2:控制器错误)
     */
    int moveTo(float theta, float rho);
    
    /**
     * 移动到指定的步数位置
     * @param thetaSteps 角度步数
     * @param rhoSteps 半径步数
     * @return 执行结果状态码 (0:成功, 1:系统休眠, 2:控制器错误)
     */
    int moveToSteps(long thetaSteps, long rhoSteps);
    
    // ==================== 运动参数设置命令 ====================
    
    /**
     * 设置绘图速度
     * @param speed 速度(步/秒)
     * @return 执行结果状态码 (0:成功, 1:控制器错误)
     */
    int setDrawingSpeed(float speed);
    
    /**
     * 设置加速度
     * @param acceleration 加速度(步/秒²)
     * @return 执行结果状态码 (0:成功, 1:控制器错误)
     */
    int setAcceleration(float acceleration);
    
    /**
     * 设置补偿系数
     * @param factor 补偿系数
     * @return 执行结果状态码 (0:成功, 1:控制器错误)
     */
    int setCompensationFactor(float factor);
    
    /**
     * 设置旋转轴每圈步数
     * @param steps 步数
     * @return 执行结果状态码 (0:成功, 1:控制器错误)
     */
    int setRotationStepsPerRev(int steps);
    
    /**
     * 设置半径轴最大步数
     * @param steps 步数
     * @return 执行结果状态码 (0:成功, 1:控制器错误)
     */
    int setRadiusMaxSteps(int steps);
    
    // ==================== LED控制命令 ====================
    
    /**
     * 启用WS2812灯带
     * @return 执行结果状态码 (0:成功, 1:LED管理器错误)
     */
    int enableWS2812();
    
    /**
     * 禁用WS2812灯带
     * @return 执行结果状态码 (0:成功, 1:LED管理器错误)
     */
    int disableWS2812();
    
    /**
     * 设置灯带亮度
     * @param brightness 亮度(0-255)
     * @return 执行结果状态码 (0:成功, 1:LED管理器错误)
     */
    int setBrightness(int brightness);
    
    /**
     * 设置绘图灯光效果
     * @param effectId 效果ID
     * @return 执行结果状态码 (0:成功, 1:LED管理器错误)
     */
    int setDrawingEffect(int effectId);
    
    /**
     * 设置绘图颜色
     * @param r 红色值(0-255)
     * @param g 绿色值(0-255)
     * @param b 蓝色值(0-255)
     * @return 执行结果状态码 (0:成功, 1:LED管理器错误)
     */
    int setDrawingColor(int r, int g, int b);
    
    /**
     * 设置绘图亮度
     * @param brightness 亮度值(0-255)
     * @return 执行结果状态码 (0:成功, 1:LED管理器错误)
     */
    int setDrawingBrightness(int brightness);
    
    /**
     * 设置绘图效果速度
     * @param speed 速度值(1-10)
     * @return 执行结果状态码 (0:成功, 1:LED管理器错误)
     */
    int setDrawingEffectSpeed(int speed);
    
    /**
     * 设置全局LED亮度
     * @param brightness 亮度值(0-255)
     * @return 执行结果状态码 (0:成功, 1:LED管理器错误)
     */
    int setGlobalBrightness(int brightness);
    
    /**
     * 启用/禁用WS2812灯带
     * @param enable true:启用, false:禁用
     * @return 执行结果状态码 (0:成功, 1:LED管理器错误)
     */
    int enableLED(bool enable);
    
    /**
     * 获取LED状态信息
     * @return JSON格式的LED状态信息
     */
    String getLEDStatus();
    
    // ==================== 系统状态查询 ====================
    
    /**
     * 获取系统状态JSON
     * @return JSON格式的系统状态信息
     */
    String getSystemStatusJson();
    
    /**
     * 获取设备信息JSON
     * @return JSON格式的设备信息
     */
    String getDeviceInfoJson();
    
    /**
     * 获取当前位置信息JSON
     * @return JSON格式的位置信息
     */
    String getPositionInfoJson();
    
    /**
     * 获取运动参数信息JSON
     * @return JSON格式的运动参数信息
     */
    String getMotionParametersJson();
    
    /**
     * 执行状态查询命令 (MQTT和串口通用)
     * @return JSON格式的状态信息
     */
    String executeStatusCommand();
    
    /**
     * 执行设备信息查询命令 (MQTT和串口通用)
     * @return JSON格式的设备信息
     */
    String executeInfoCommand();
    
    // ==================== 辅助方法 ====================
    
    /**
     * 检查是否可以执行电机相关命令
     * @param commandName 命令名称
     * @return 是否允许执行
     */
    bool canExecuteMotorCommand(const String& commandName);
    
    /**
     * 智能加载默认图案
     * @return 执行结果状态码 (0:成功, 1:无图案, 2:加载失败)
     */
    int loadDefaultOrLastPattern();
    
    /**
     * 保存最后使用的图案
     * @param patternName 图案文件名
     * @return 是否保存成功
     */
    bool saveLastUsedPattern(const String& patternName);
    
    /**
     * 加载最后使用的图案
     * @return 最后使用的图案文件名
     */
    String loadLastUsedPattern();
    
    /**
     * 获取错误码对应的描述信息
     * @param errorCode 错误码
     * @return 错误描述
     */
    String getErrorDescription(int errorCode);
    
    // ==================== 系统监控命令 ====================
    
    /**
     * 执行任务信息命令
     * @return 执行结果状态码 (0:成功)
     */
    int executeTaskInfoCommand();
    
    /**
     * 执行核心信息命令
     * @return 执行结果状态码 (0:成功)
     */
    int executeCoreInfoCommand();
    
    /**
     * 执行内存信息命令
     * @return 执行结果状态码 (0:成功)
     */
    int executeMemInfoCommand();
    
    // 已删除未实现的函数
    
    // ==================== 自动播放命令 ====================
    
    /**
     * 执行自动播放启用/禁用命令
     * @param enabled 是否启用自动播放
     * @return 执行结果状态码 (0:成功)
     */
    int executeAutoPlayEnableCommand(bool enabled);
    
    /**
     * 执行设置自动播放时间命令
     * @param minutes 展示时间（分钟）
     * @return 执行结果状态码 (0:成功, 1:参数错误)
     */
    int executeAutoPlayTimeCommand(int minutes);
    
    /**
     * 执行设置自动播放模式命令
     * @param useSweepMode 是否使用扫图模式
     * @return 执行结果状态码 (0:成功)
     */
    int executeAutoPlayModeCommand(bool useSweepMode);
    
    /**
     * 执行显示自动播放状态命令
     * @return 执行结果状态码 (0:成功)
     */
    int executeAutoPlayStatusCommand();
    
    // ==================== 自动恢复命令 ====================
    
    /**
     * 执行启用自动恢复命令
     * @return 执行结果状态码 (0:成功)
     */
    int executeAutoResumeEnableCommand();
    
    /**
     * 执行设置自动恢复时间命令
     * @return 执行结果状态码 (0:成功, 1:参数错误)
     */
    int executeAutoResumeTimeCommand();
    
    /**
     * 执行显示自动恢复状态命令
     * @return 执行结果状态码 (0:成功)
     */
    int executeAutoResumeStatusCommand();
    
    // ==================== 电机管理命令 ====================
    
    /**
     * 执行电机自动管理命令
     * @param enabled 是否启用自动管理
     * @return 执行结果状态码 (0:成功, 1:参数错误)
     */
    int executeAutoManageCommand(bool enabled);
    
    /**
     * 执行设置电机超时命令
     * @param timeoutSeconds 超时时间(秒)
     * @return 执行结果状态码 (0:成功, 1:参数范围错误)
     */
    int executeTimeoutCommand(int timeoutSeconds);
    
    // 已删除未实现的函数
    
    /**
     * 执行位置查询命令
     * @return 执行结果状态码 (0:成功)
     */
    int executePositionCommand();
    
    // ==================== 图案内存命令 ====================
    
    // 已删除未实现的函数
    
    // ==================== 文件管理命令 ====================
    
    // 已删除未实现的函数
    
    // ==================== 帮助和辅助功能 ====================
    
    /**
     * 执行帮助命令
     * @return 执行结果状态码 (0:成功)
     */
    int executeHelpCommand();
    
    /**
     * 执行详细状态显示命令（为串口提供格式化输出）
     * @return 执行结果状态码 (0:成功)
     */
    int executeDetailedStatusCommand();
    
    /**
     * 执行按钮短按开始/停止处理
     * @return 执行结果状态码 (0:成功, 1:系统休眠, 2:无图案)
     */
    int executeShortPressStartStop();
    
    // ==================== 图案命令处理 ====================
    
    /**
     * 执行图案文件列表命令
     * @return 执行结果状态码 (0:成功, 1:SD卡错误)
     */
    int executeListCommand();
    
    // ==================== 上下文感知命令处理 ====================
    
    /**
     * 通用命令上下文处理
     * 相同命令=继续，不同命令=切换
     * @param command 输入的命令
     * @return 执行结果码
     */
    int executeWithContext(const String& command);
    
    /**
     * 判断是否为绘图相关命令
     * @param command 命令字符串
     * @return true=绘图命令, false=其他命令
     */
    bool isDrawingCommand(const String& command);
    
    /**
     * 获取继续命令映射
     * @param lastCommand 上次执行的命令
     * @param currentCommand 当前输入的命令
     * @return 实际应该执行的命令
     */
    String getContinueCommandMapping(const String& lastCommand, const String& currentCommand);

private:
    // ==================== 内部绘图实现 ====================
    
    /**
     * 在绘图循环中处理串口命令（简化版本，只处理关键命令）
     * @return true如果需要停止绘图
     */
    bool handleSerialInputDuringDrawing();
    
    // ==================== 优化辅助函数 ====================
    
    /**
     * 验证并加载图案
     * @return 0:成功, 其他:错误码
     */
    int validateAndLoadPattern();
    
    /**
     * 执行归零操作的通用逻辑
     * @return 0:成功, 其他:错误码
     */
    int performHomingOperation();
    
    /**
     * 重置绘图状态为空闲
     */
    void resetDrawingStateToIdle();
    
    /**
     * 优化的LED更新逻辑
     * @param forceUpdate 是否强制更新
     */
    void updateLEDOptimized(bool forceUpdate = false);
    
    // ==================== 统一状态管理辅助函数 ====================
    
    /**
     * 统一的状态转换函数 - 核心状态管理逻辑
     * @param targetSystemState 目标系统状态
     * @param targetLEDStatus 目标LED状态
     * @param reason 状态转换原因
     * @param manageLEDSession 是否管理LED绘图会话
     * @param startSession 是否启动LED会话（当manageLEDSession为true时有效）
     */
    void transitionToState(SystemState targetSystemState, 
                          LEDStatus targetLEDStatus, 
                          const String& reason,
                          bool manageLEDSession = false,
                          bool startSession = false);
    
    /**
     * 获取系统状态字符串描述
     */
    String getSystemStateString(SystemState state);
    
    /**
     * 设置系统维护状态并启动LED绘图会话
     */
    void setMaintenanceStateAndStartLED();
    
    /**
     * 设置系统空闲状态并结束LED绘图会话
     * @param endDrawingSession 是否结束LED绘图会话，默认true
     */
    void setIdleStateAndEndLED(bool endDrawingSession = true);
    
    /**
     * 设置系统绘图状态并启动LED绘图会话
     */
    void setDrawingStateAndStartLED();
    
    /**
     * 设置系统归零状态
     */
    void setHomingState();
    
    /**
     * 设置系统维护状态（不影响LED会话状态）
     */
    void setMaintenanceStateOnly();
    
    /**
     * 设置暂停状态（保持系统状态，只改变LED状态）
     */
    void setPausedState();
    
    /**
     * 设置紧急停止状态
     * @param reason 紧急停止原因
     */
    void setEmergencyState(const String& reason);
    
    /**
     * 防死机辅助函数：检查系统健康状态
     * @param functionName 调用函数名称
     * @param loopCounter 循环计数器
     * @param startTime 开始时间
     * @return true=系统正常，false=需要停止
     */
    bool checkSystemHealth(const String& functionName, int loopCounter, unsigned long startTime);
    
    /**
     * 快速系统状态检查 - 减少重复代码
     */
    bool quickSystemCheck(const String& operation);
    
    /**
     * 快速图案检查 - 减少重复代码
     */
    bool quickPatternCheck();
    
    // ==================== 统一的验证和处理函数 ====================
    
    /**
     * 统一系统状态验证函数
     */
    bool validateSystemState();
    
    /**
     * 统一错误处理函数
     */
    void handleError(int errorCode, const char* context);
    
    /**
     * 统一的命令前置检查
     */
    bool preExecuteCheck(const String& command);
    
    /**
     * 统一的命令后置处理
     */
    void postExecuteProcess(const String& command, int result);
    
    /**
     * 统一的图案验证和加载函数
     */
    int validateAndEnsurePattern();
    
    /**
     * 统一的绘图前准备检查
     */
    int prepareForDrawing(const String& command);
    
    /**
     * 统一的电机操作函数
     */
    int executeMotorOperation(const char* operation, bool enableOperation);
    
    /**
     * 统一的自动播放配置验证函数
     */
    bool validateAutoPlayParams(int minutes, const char* context);
    
    // ==================== 高性能命令处理 ====================
    
    /**
     * 高性能命令解析器
     */
    CommandType parseCommandFast(const String& command);
    
    /**
     * 根据命令类型执行对应操作
     */
    int executeCommandByType(CommandType cmdType);
    
    /**
     * 批量处理执行函数
     */
    int executeBatchCommands(const String commands[], size_t count);
    
    /**
     * 优化的网络任务处理
     */
    void executeNetworkTaskOptimized();
    
    /**
     * 批量状态更新函数
     */
    void updateDrawingProgress(int pointCount);
    

    
    /**
     * 创建优化的JSON文档
     * @param size 缓冲区大小
     * @return DynamicJsonDocument
     */
    DynamicJsonDocument createOptimizedJsonDoc(int size = 512);
    
    /**
     * 通用的扫图准备流程实现
     * @param patternMode 图案模式："prev", "next", 或 "current"
     * @return 执行结果状态码 (0:成功, 1:系统休眠, 2:控制器错误)
     */
    int executeSweepAndPrepareWithPattern(const String& patternMode);
    
    // 已弃用的函数声明
    
    
    // 已删除未实现的函数
    
    /**
     * 执行流式绘图
     */
    int executeStreamDrawing();
};

#endif // COMMAND_EXECUTOR_H
